
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<HTML>

<HEAD>
   <TITLE>furnsh_c</TITLE>
</HEAD>

<BODY style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">
<A name="TOP"></A>

<table style="text-align: left; margin-left: auto; margin-right: auto; width: 800px;"
 border="0" cellpadding="5" cellspacing="2">
  <tbody>
    <tr>
      <td style="background-color: rgb(153, 153, 153); vertical-align: middle; text-align: center;">
      <div align="right"> 
      <small><small><a href="index.html">Index Page</a></small></small>
      </div>
      <b>furnsh_c</b> </td>
    </tr>

    <tr>
      <td style="vertical-align: top;">

<small><div align="center">
<A HREF="index.html#A">A</A>&nbsp;
<A HREF="index.html#B">B</A>&nbsp;
<A HREF="index.html#C">C</A>&nbsp;
<A HREF="index.html#D">D</A>&nbsp;
<A HREF="index.html#E">E</A>&nbsp;
<A HREF="index.html#F">F</A>&nbsp;
<A HREF="index.html#G">G</A>&nbsp;
<A HREF="index.html#H">H</A>&nbsp;
<A HREF="index.html#I">I</A>&nbsp;
<A HREF="index.html#J">J</A>&nbsp;
<A HREF="index.html#K">K</A>&nbsp;
<A HREF="index.html#L">L</A>&nbsp;
<A HREF="index.html#M">M</A>&nbsp;
<A HREF="index.html#N">N</A>&nbsp;
<A HREF="index.html#O">O</A>&nbsp;
<A HREF="index.html#P">P</A>&nbsp;
<A HREF="index.html#Q">Q</A>&nbsp;
<A HREF="index.html#R">R</A>&nbsp;
<A HREF="index.html#S">S</A>&nbsp;
<A HREF="index.html#T">T</A>&nbsp;
<A HREF="index.html#U">U</A>&nbsp;
<A HREF="index.html#V">V</A>&nbsp;
<A HREF="index.html#W">W</A>&nbsp;
<A HREF="index.html#X">X</A>&nbsp;
</div></small>
       <br>
       <table style="text-align: left; width: 60%; margin-left: auto; margin-right: auto;"
       border="0" cellspacing="2" cellpadding="2">
        <tbody>
          <tr>
            <td style="width: 50%; text-align: center;">
            <small>
              <a href="#Procedure">Procedure<br></a>
              <a href="#Abstract">Abstract<br></a>
              <a href="#Required_Reading">Required_Reading<br></a>
              <a href="#Keywords">Keywords<br></a>
              <a href="#Brief_I/O">Brief_I/O<br></a>
              <a href="#Detailed_Input">Detailed_Input<br></a>

              </small>
              </td>
              <td style="vertical-align: top; width: 50%; text-align: center;">
              <small>               <a href="#Detailed_Output">Detailed_Output<br></a>
              <a href="#Parameters">Parameters<br></a>
              <a href="#Exceptions">Exceptions<br></a>
              <a href="#Files">Files<br></a>
              <a href="#Particulars">Particulars<br></a>
              <a href="#Examples">Examples<br></a>

              </small>
              </td>
              <td style="vertical-align: top; width: 50%; text-align: center;">
              <small>               <a href="#Restrictions">Restrictions<br></a>
              <a href="#Literature_References">Literature_References<br></a>
              <a href="#Author_and_Institution">Author_and_Institution<br></a>
              <a href="#Version">Version<br></a>
              <a href="#Index_Entries">Index_Entries<br></a>
             </small>
            </td>
          </tr>
        </tbody>
</table>

<h4><a name="Procedure">Procedure</a></h4>
<PRE>
   void furnsh_c ( ConstSpiceChar  * file ) 

</PRE>
<h4><a name="Abstract">Abstract</a></h4>
<PRE>
 
   Load one or more SPICE kernels into a program.
</PRE>
<h4><a name="Required_Reading">Required_Reading</a></h4>
<PRE>
 
    None. 
 </PRE>
<h4><a name="Keywords">Keywords</a></h4>
<PRE>
 
    UTILITY 
 

</PRE>
<h4><a name="Brief_I/O">Brief_I/O</a></h4>
<PRE>
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   file       I   Name of SPICE kernel file (text or binary). 
 </PRE>
<h4><a name="Detailed_Input">Detailed_Input</a></h4>
<PRE>
 
   file       is the name of a SPICE kernel file. The file may be
              either binary or text. If the file is a binary SPICE
              kernel it will be loaded into the appropriate SPICE
              subsystem.  If `file' is a SPICE text kernel it will be
              loaded into the kernel pool.  If `file' is a SPICE
              meta-kernel containing initialization instructions
              (through use of the correct kernel pool variables), the
              files specified in those variables will be loaded into
              the appropriate SPICE subsystem.

              The SPICE text kernel format supports association of
              names and data values using a &quot;keyword = value&quot; format.
              The keyword-value pairs thus defined are called &quot;kernel
              variables.&quot; 

              While any information can be placed in a text kernel 
              file, the following string valued kernel variables are 
              recognized by SPICE as meta-kernel keywords:
 
                 KERNELS_TO_LOAD 
                 PATH_SYMBOLS 
                 PATH_VALUES 
 
              Each kernel variable is discussed below. 
 
                 KERNELS_TO_LOAD   is a list of SPICE kernels to be 
                                   loaded into a program.  If file 
                                   names do not fit within the kernel 
                                   pool 80 character limit, they may be 
                                   continued to subsequent array 
                                   elements by placing the continuation 
                                   character ('+') at the end of an 
                                   element and then placing the 
                                   remainder of the file name in the 
                                   next array element.  (See the 
                                   examples below for an illustration 
                                   of this technique or consult the 
                                   routine <a href="stpool_c.html">stpool_c</a> for further 
                                   details.) 
    
                                   Alternatively you may use a
                                   PATH_SYMBOL (see below) to
                                   substitute for some part of a file
                                   name.
    
                 PATH_SYMBOLS      is a list of strings (without 
                                   embedded blanks), which if 
                                   encountered following the '$' 
                                   character will be replaced with the 
                                   corresponding PATH_VALUES string. 
                                   Note that PATH_SYMBOLS are 
                                   interpreted only in the 
                                   KERNELS_TO_LOAD variable. There must 
                                   be a one-to-one correspondence 
                                   between the values supplied for 
                                   PATH_SYMBOLS and PATH_VALUES. 
    
                 PATH_VALUES       is a list of expansions to use when 
                                   PATH_SYMBOLS are encountered.  See 
                                   the examples section for an 
                                   illustration of use of PATH_SYMBOLS 
                                   and PATH_VALUES. 
 
              These kernel pool variables persist within the kernel 
              pool only until all kernels associated with the 
              variable KERNELS_TO_LOAD have been loaded.  Once all 
              specified kernels have been loaded, the variables 
              KERNELS_TO_LOAD, PATH_SYMBOLS and PATH_VALUES are 
              removed from the kernel pool. 
 </PRE>
<h4><a name="Detailed_Output">Detailed_Output</a></h4>
<PRE>
 
   None. The routine loads various SPICE kernels for use by your 
   application. 
 </PRE>
<h4><a name="Parameters">Parameters</a></h4>
<PRE>
 
   None. 
 </PRE>
<h4><a name="Exceptions">Exceptions</a></h4>
<PRE>
 
   1) If a problem is encountered while trying to load `file', it will
      be diagnosed by a routine from the appropriate SPICE subsystem.
 
   2) If the input `file' is a meta-kernel and some file in 
      the KERNELS_TO_LOAD assignment cannot be found, the error 
      SPICE(CANTFINDFILE) will be signaled and the routine will 
      return.  Any files loaded prior to encountering the missing
      file will remain loaded. 
 
   3) If an error is encountered while trying to load one of the files
      specified by the KERNELS_TO_LOAD assignment, the routine will
      discontinue attempting to perform any other tasks and return.
  
   4) If a PATH_SYMBOLS assignment is specified without a corresponding
      PATH_VALUES assignment, the error SPICE(NOPATHVALUE) will be
      signaled.
 
   5) If a meta-kernel is supplied that contains instructions
      specifying that another meta-text kernel be loaded, the error
      SPICE(RECURSIVELOADING) will be signaled.
 
   6) If the input `file' argument pointer is null, the error
      SPICE(NULLPOINTER) will be signaled.
      
   7) If the input `file' argument is the empty string, the error
      SPICE(EMPTYSTRING) will be signaled.

   6) The error 'SPICE(BADVARNAME)' signals if the a pool 
      variable name length exceeds 32.   
   </PRE>
<h4><a name="Files">Files</a></h4>
<PRE>
 
   The input file is examined and loaded into the appropriate 
   SPICE subsystem.  If the file is a meta-kernel, any kernels
   specified by the KERNELS_TO_LOAD keyword (and if present,
   the PATH_SYMBOLS and PATH_VALUES keywords) are loaded as well.
 </PRE>
<h4><a name="Particulars">Particulars</a></h4>
<PRE>
 
   This routine provides a uniform interface to the SPICE kernel 
   loading systems.  It allows you to easily assemble a list of 
   SPICE kernels required by your application and to modify that set 
   without modifying the source code of programs that make use of 
   these kernels. 

   Text kernels input to this routine need not have native line
   terminators for the platform. Lower level CSPICE routines can
   read and process non-native text files. This functionality does
   not exist in the Fortran SPICELIB.

   Only text kernel readers include the non-native read capability,
   (<a href="ldpool_c.html">ldpool_c</a> and <b>furnsh_c</b>), the generic text file line reader, <a href="rdtext_c.html">rdtext_c</a>
   requires native text files.
   
   Please refer to kernel.req for additional information.

   Kernel pool variable names are restricted to a length of 32
   characters or less.
</PRE>
<h4><a name="Examples">Examples</a></h4>
<PRE>
 
   Example 1
   --------- 

   Load the leapseconds kernel naif0007.tls and the planetary ephemeris
   SPK file de405s.bsp.

       <b>furnsh_c</b> ( &quot;naif0007.tls&quot; );
       <b>furnsh_c</b> ( &quot;de405s.bsp&quot;   );


   Example 2 
   --------- 
 
   This example illustrates how you could create a meta-kernel file for
   a program that requires several text and binary kernels.
 
   First create a list of the kernels you need in a text file as
   shown below.
 
      \begintext 
 
         Here are the SPICE kernels required for my application 
         program. 
 
         Note that kernels are loaded in the order listed. Thus we 
         need to list the highest priority kernel last. 
 
 
      \begindata 
      
      KERNELS_TO_LOAD = ( '/home/mydir/kernels/spk/lowest_priority.bsp', 
                          '/home/mydir/kernels/spk/next_priority.bsp', 
                          '/home/mydir/kernels/spk/highest_priority.bsp', 
                          '/home/mydir/kernels/text/leapsecond.ker', 
                          '/home/mydir/kernels+',
                          '/custom+', 
                          '/kernel_data/constants.ker',
                          '/home/mydir/kernels/text/sclk.tsc', 
                          '/home/mydir/kernels/ck/c-kernel.bc' ) 
 
 
   Note that the file name
 
      /home/mydir/kernels/custom/kernel_data/constants.ker 
 
   is continued across several lines in the right hand side of the
   assignment of the kernel variable KERNELS_TO_LOAD. 
 
   Once you've created your list of kernels, call <b>furnsh_c</b> near the
   beginning of your application program to load the meta-kernel
   automatically at program start up.
 
      <b>furnsh_c</b> ( &quot;myfile.txt&quot; );

   This will cause each of the kernels listed in your meta-kernel
   to be loaded.
 
 
   Example 3
   --------- 
 
   This example illustrates how you can simplify the previous 
   kernel list by using PATH_SYMBOLS. 
 
 
      \begintext 
 
         Here are the SPICE kernels required for my application 
         program. 
 
         We are going to let A substitute for the directory that
         contains SPK files; B substitute for the directory that
         contains C-kernels; and C substitute for the directory that
         contains text kernels.  And we'll let D substitute for
         a &quot;custom&quot; directory that contains a special planetary
         constants kernel made just for our mission.
 
         Note that the order in which we list our PATH_VALUES must be 
         the same order that the corresponding PATH_SYMBOLS are 
         listed. 
          
 
      \begindata 
      
      PATH_VALUES  = ( '/home/mydir/kernels/spk', 
                       '/home/mydir/kernels/ck', 
                       '/home/mydir/kernels/text',
                       '/home/mydir/kernels/custom/kernel_data' ) 
 
      PATH_SYMBOLS = ( 'A', 
                       'B', 
                       'C'
                       'D'  ) 
 
 
      KERNELS_TO_LOAD = (  '$A/lowest_priority.bsp', 
                           '$A/next_priority.bsp', 
                           '$A/highest_priority.bsp', 
                           '$C/leapsecond.ker', 
                           '$D/constants.ker',
                           '$C/sclk.tsc', 
                           '$B/c-kernel.bc'         )
 </PRE>
<h4><a name="Restrictions">Restrictions</a></h4>
<PRE>
 
   None. 
 </PRE>
<h4><a name="Literature_References">Literature_References</a></h4>
<PRE>
   None. 
 </PRE>
<h4><a name="Author_and_Institution">Author_and_Institution</a></h4>
<PRE>
   
   C.H. Acton      (JPL)
   N.J. Bachman    (JPL)
   W.L. Taber      (JPL) 
 </PRE>
<h4><a name="Version">Version</a></h4>
<PRE>
   -CSPICE Version 1.3.2,  10-FEB-2010 (EDW)

      Corrected header section order. Added mention of the
      restriction on kernel pool variable names to 32 characters
      or less.

   -CSPICE Version 1.0.4, 17-OCT-2005 (EDW)

      Added text to Particulars section informing of the
      non-native kernel text file reading capability.

   -CSPICE Version 1.0.3, 29-JUL-2003 (NJB) (CHA)

      Numerous updates to improve clarity.  Some corrections
      were made.
 
   -CSPICE Version 1.0.2, 03-JUL-2002 (NJB) 
   
      Documentation fix:  corrected second code example.  The example
      previously used the kernel variable PATH_NAMES; that name has been
      replaced with the correct name PATH_VALUES.
 
   -CSPICE Version 1.0.1, 13-APR-2000 (NJB) 
   
      Replaced single quotes with double quotes in a code example.

   -CSPICE Version 1.0.0, 01-SEP-1999 (NJB) (WLT)
</PRE>
<h4><a name="Index_Entries">Index_Entries</a></h4>
<PRE>
 
   Load SPICE data from a list of items 
 </PRE>
<h4>Link to routine furnsh_c source file <a href='../../../src/cspice/furnsh_c.c'>furnsh_c.c</a> </h4>

      </td>
    </tr>
  </tbody>
</table>

   <pre>Wed Jun  9 13:05:23 2010</pre>

</body>
</html>

